<?xml version="1.0" encoding="UTF-8"?>
<!--

       Copyright 2006-2022 the original author or authors.

       Licensed under the Apache License, Version 2.0 (the "License");
       you may not use this file except in compliance with the License.
       You may obtain a copy of the License at

          https://www.apache.org/licenses/LICENSE-2.0

       Unless required by applicable law or agreed to in writing, software
       distributed under the License is distributed on an "AS IS" BASIS,
       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
       See the License for the specific language governing permissions and
       limitations under the License.

-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>Implementing Plugins</title>
  <link rel="stylesheet" type="text/css" href="../mbgstyle.css" />
</head>
<body>
<h1>Implementing Plugins</h1>
<p>Plugins can be used to modify or add to the objects that are generated by MyBatis Generator.
Plugins must implement the interface
<code>org.mybatis.generator.api.Plugin</code>.  The plugin interface contains many
methods that are called in different phases of the code generation process.  Implementing the
entire interface is generally not needed for any particular plugin.  Therefore, most plugins should extend
the adapter class <code>org.mybatis.generator.api.PluginAdapter</code>.  The adapter
class provides basic plugin support, and implements no-operation methods for most of the
interface methods (similar to Swing adapter classes).</p>

<p>MyBatis Generator supplies several plugins (all are in the package
<code>org.mybatis.generator.plugins</code>).  The supplied plugins demonstrate
different types of tasks that can be accomplished with plugins.  Source
code for the plugins is available with the downloads, or can be viewed
online
<a target="_blank" href="https://github.com/mybatis/generator/tree/master/core/mybatis-generator-core/src/main/java/org/mybatis/generator/plugins">
here</a>.</p>

<h2>Plugin Lifecycle</h2>
<p>Plugins have a lifecycle.  Plugins are created during the initialization of the code
generation process and are called, in order, in different phases of the process.  The following
list shows the basic lifecycle of a plugin:</p>
<ol type="1">
  <li>Plugin created through the default constructor</li>
  <li><code>setContext</code> method called</li>
  <li><code>setProperties</code> method called</li>
  <li><code>validate</code> method called.  If this method returns <code>false</code>,
      then no further methods in the plugin will be called</li>
  <li>For each table in the configuration:
    <ol type="a">
      <li><code>initialized</code> method called</li>
      <li>Java Client Methods:<sup>1,2</sup>
        <ol type="i">
          <li><code>clientXXXMethodGenerated(Method, TopLevelClass, IntrospectedTable)</code> - these methods
              are called as each method of a Java client implementation class is generated.</li>
          <li><code>clientXXXMethodGenerated(Method, Interface, IntrospectedTable)</code> - these methods
              are called as each method of the Java client interface is generated.</li>
          <li><code>clientGenerated(Interface, TopLevelClass, IntrospectedTable)</code> method called</li>
        </ol>
      </li>
      <li>Model Methods:<sup>1</sup>
        <ol type="i">
          <li><code>modelFieldGenerated</code>, <code>modelGetterMethodGenerated</code>,
              <code>modelSetterMethodGenerated</code> for each field in the class</li>
          <li><code>modelExampleClassGenerated(TopLevelClass, IntrospectedTable)</code></li>
          <li><code>modelPrimaryKeyClassGenerated(TopLevelClass, IntrospectedTable)</code></li>
          <li><code>modelBaseRecordClassGenerated(TopLevelClass, IntrospectedTable)</code></li>
          <li><code>modelRecordWithBLOBsClassGenerated(TopLevelClass, IntrospectedTable)</code></li>
        </ol>
      </li>
      <li>SQL Map Methods:<sup>1</sup>
        <ol type="i">
          <li><code>sqlMapXXXElementGenerated(XmlElement, IntrospectedTable)</code> - these methods
              are called as each element of the SQL map is generated</li>
          <li><code>sqlMapDocumentGenerated(Document, IntrospectedTable)</code></li>
          <li><code>sqlMapDocument(GeneratedXmlFile, IntrospectedTable)</code></li>
        </ol>
      </li>
      <li><code>contextGenerateAdditionalJavaFiles(IntrospectedTable)</code> method called</li>
      <li><code>contextGenerateAdditionalXmlFiles(IntrospectedTable)</code> method called</li>
    </ol>
  </li>
  <li><code>contextGenerateAdditionalJavaFiles()</code> method called</li>
  <li><code>contextGenerateAdditionalXmlFiles()</code> method called</li>
</ol>

<p><b>Notes:</b><br/>
<sup>1</sup> - These methods will be called by the packaged code generators.  If you supply
 a custom code generator, then these methods will only be called if the custom code generator
 calls them.<br/>
<sup>2</sup> - The Java client methods will only be called is a Java client generator is configured.
</p>

<h2>Coding Plugins</h2>
<p>The best way to implement a plugin is to extend the
<code>org.mybatis.generator.api.PluginAdapter</code> class and override
only the specific methods you need in your plugin.</p>
<p>Methods in the plugin interface can be used to modify code generated by default, or
to add additional generated code.  Examples of things that can be accomplished with
plugins are:</p>
<ul>
  <li>Add custom annotations to generated methods</li>
  <li>Add additional methods to a generated class</li>
  <li>Add additional elements to a generated XML file</li>
  <li>Generate additional Java files</li>
  <li>Generate additional XML files</li>
</ul>

<p>The <code>contextXXX</code> methods will always be called.  Other methods are called
by the packaged code generators - and only if the rules for a table would
cause the generation of a particular element.  For example, the
<code>modelPrimaryKeyClassGenerated(TopLevelClass, IntrospectedTable)</code>
method will not be called if the table does not have a primary key.</p>

<p>Methods that return a <code>boolean</code> can be used to bypass code generation.
If any of these methods return <code>false</code>, then the related item will
not be added to the generated code.  If there is more than one plugin configured,
then the first plugin to return false from a method will cause MyBatis Generator to stop calling
that method in all other plugins.</p>

<p>If you have an idea for a plugin, feel free to ask a question about it on
the user list.  We're here to help!</p>
</body>
</html>
